home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / cpp_libs / perlcl16.lha / perlclass1.6 / perlclass.readme < prev    next >
Text File  |  1992-11-06  |  9KB  |  307 lines
  1. For support Email to jegm@sgi.com
  2.  
  3. This is not thoroughly tested, so I would welcome bug reports for
  4. a while! Also comments are always welcome.
  5.  
  6. The latest version of PerlClass is always available via anonymous
  7. FTP from samadams.princeton.edu in /u/ftp/pub/pec
  8.  
  9. Thanks to Michael Golan <mg@Princeton.EDU> for making the site
  10. available.
  11.  
  12. Introducing PerlClass
  13. =====================
  14.  
  15. PerlClass is a c++ class library that implements my favourite Perl
  16. constructs.  Obviously I can't duplicate all the functionality, and
  17. wouldn't need to as Perl already exists!! However I find this useful,
  18. because it allows me to do Perl-like things in my programs.
  19.  
  20. This Code is not copyright, use as you will.  The regexp code is by
  21. Henry Spencer, see the comments for Copyright info.  The only changes I
  22. have made are to the header file, by adding a c++ prototype field.
  23.  
  24.  
  25. The Class Hierarchy and member functions are:-
  26.  
  27. // functionality is that of perl unless otherwise noted
  28. class PerlList<T>
  29.     T& operator[]
  30.     void reset()
  31.     int scalar()
  32.     T pop()
  33.     void push(T)
  34.     void push(PerlList<T>)
  35.     T shift()
  36.     int unshift(T)
  37.     int unshift(PerlList<T>)
  38.     PerlList<T> reverse()
  39.     PerlList<T> splice(offset, len, PerlList<T>)
  40.     PerlList<T> splice(offset, len)
  41.     PerlList<T> splice(offset)
  42.     PerlList<T> sort()
  43.  
  44. >>>>class PerlStringList // everything PerlList does and ...
  45.         int split(str [,pat] [,limit])
  46.     PerlString join([pat])
  47.     int m(exp, targ)      // makes list of sub exp matches
  48.     PerlStringList grep(exp) // returns matches in list
  49.  
  50. class PerlString
  51.     int length()
  52.     char chop()
  53.     int index(PerlString [, offset])    
  54.     int rindex(PerlString [, offset])
  55.     PerlString substr(offset [, len])    // works as lvalue as well
  56.     operator[]
  57.     operator<
  58.     operator>
  59.     operator<=
  60.     operator>=
  61.     operator==
  62.     operator!=
  63.     operator+        // concatenation (equivalent of . )
  64.     operator+=        // like .=
  65.     int m(exp)                 // equiv to m/.../
  66.     int m(exp, PerlStringList&) // equiv to @s = m/.(..)../
  67.     int tr(exp, rep [,opts]) // equiv to tr/.../.../
  68.     int s(exp, rep [,opts]) // equiv to s/../../
  69.  
  70. Associative array and helpers
  71. =============================
  72.  
  73. class Binar<T>    // a key, value pair
  74.     T& value()
  75.     PerlString& key()
  76.  
  77. class Assoc<T>    // an associateive array, loosely based on the perl one
  78.     T& operator(PerlString) // equivalent to perl $assoc{"one"} = value
  79.     Binar& operator[n]      // returns n'th entry in associative array
  80.     PerlStringList keys()   // returns a list of keys
  81.     PerlList<T> values()    // returns a list of values
  82.     int isin(PerlString)    // tests if key is in assoc array
  83.     T adelete(PerlString)    // deletes given key/value
  84.  
  85. Other Classes
  86. =============
  87.  
  88. VarString    - A variable length string class, used in PerlString.
  89.  
  90. PerlListBase<T> - is the base class for PerlList and handles the
  91.           auto expanding dynamic array, optimized for
  92.           prepending and appending data.
  93.  
  94. TempString - makes a copy of a string, and can return a char *
  95.          and will free the storage when done. Something like a
  96.          cross between strsave() and alloca().
  97.  
  98. Regexp - Handles the interface to the regular expression library
  99.          being used.
  100.  
  101. Range - Simple class to maintain a range, just makes things easier.
  102.          
  103. NOTES
  104. =====
  105. This must be compiled with a 3.0 or greater c++ compiler that can
  106. handle Templates and nested classes.
  107.  
  108. It has been tested on Borland c++ v3.1 and USL-based 3.0.
  109. GCC doesn't like the Copy constructor syntax in template classes, and
  110. gives an assert error as well.
  111.  
  112. To build:
  113.  
  114. compile perlclass.c++ and regex.c. Link in with your App.
  115. Include perlclass.h, (and perlassoc.h if used).
  116.  
  117. > cc -c regex.c
  118. > CC -c perlclass.c++
  119. > CC yourapp.c++ perlclass.o regex.o -o yourapp
  120.  
  121. To test:
  122.  
  123. > CC -DTEST perltest.c++ perlclass.c++ regex.o -o perltest
  124. > perltest > x
  125. > diff x perlclass.v
  126.  
  127. regex.c is not an ANSI c file, so you will have to turn off prototype
  128. checking on your ANSI c compiler (or select kr checking).
  129.  
  130. CAVEATS (known ones that is)
  131. =======
  132. This is not an optimised implementation, by any stretch of the
  133. imagination. It is a quick and dirty, "but it works" one.
  134.  
  135. No "out of memory checking" is done, I thought I'd wait for
  136. exceptions!!
  137.  
  138. I have taken a few liberties in translating the selected Perl
  139. functionality into a class library, apologies to Larry Wall, and
  140. anyone else this may offend.  You are welcome to fix it, just tell me
  141. how you did it.
  142.  
  143. A PerlList<T> can only contain a list of type T, it cannot, as yet,
  144. have multiple types in the same list. (This is feasible but messy).
  145.  
  146. Assigning to an element of a PerlList that is greater than the current
  147. length of the PerlList will expand the list as in perl, but the values
  148. in the newly created elements will be undefined, unlike perl. Except
  149. PerlStringList which will create empty strings. Also if <T> is a class
  150. then the values will be whatever the default constructor creates.
  151.  
  152. Anything that you make a PerlList out of must define an operator<(),
  153. for the sort routine. Its ok if it is a dummy.
  154.  
  155. The first index of a list is always 0. (Again this could be fixed).
  156.  
  157. Unlike Perl you can also access characters within
  158. a PerlString using the '[]' syntax. But you must use substr() to
  159. change them.
  160.  
  161. Note that PerlStrings cannot have embedded '\0' like perl, this
  162. is an efficiency trade off, because '\0' as a terminator is so
  163. ingrained in c++ and c strings.
  164.  
  165. Regular Expressions
  166. -------------------
  167.  
  168. Regular expressions may be slightly different, I used the straight
  169. Henry Spencer version. I'm not sure what changes Larry made to them.
  170. (It definitely doesn't support \w \b \s \S \d \D, or global match
  171. mode). - If someone can make Larry's regexp stuff into a stand-alone
  172. package like the original regex stuff, then I'll use it!
  173.  
  174. The g & o options are not supported in the m() functions.
  175. I will try to support the 'g' option for m() in a list context.
  176.  
  177. PerlStringList::m(exp, targ) and PerlString::m(exp, list) are used to
  178. simulate $&, $0 - $9 in perl. In both cases the list gets loaded with
  179. the subexpression matches. The 0'th element is equivalent to $& in perl
  180. and the 1'st element is equivalent to $1 etc.
  181.  
  182. Note that in the PerlStringlist::m() member function, result lists are
  183. appended whereas in PerlString::m(s, list) 'list' is reset first.
  184. eg
  185. {
  186. PerlString s;
  187. PerlStringList l1, l2;
  188.  
  189.     s= "hello frobo goodbye";
  190.     l1.push("was here first1"); l2.push("was here first2");
  191.     s.m("(.*)frobo(.*)", l2); // Overwrites l with new list
  192.     l1.m("(.*)frobo(.*)", s); // appends l with new list
  193. // produces this result:
  194. // l2[0] is "hello frobo goodbye"    // equiv of $&
  195. // l2[1] is "hello "            // equiv of $1
  196. // l2[2] is " goodbye"            //        $2
  197. // and
  198. // l1[0] is "was here first"
  199. // l1[1] is "hello frobo goodbye"    // equiv of $&
  200. // l1[2] is "hello "            //          $1
  201. // l1[3] is " goodbye"            //        $2
  202. // an l1.reset() preceding the l1.m() would get rid of l1[0] in the
  203. // above example.    
  204. }
  205.  
  206. To get the exact perl semantics of the m function in a list context
  207. you can use the global m() function as follows:-
  208. {
  209. PerlStringList sl;
  210. sl = m("(..) (..)", "ab cd ef"); // sl[0] gets "ab", sl[1] gets "cd"
  211. }
  212.  
  213. Perl expressions (s/123/$&*2/e) in a substitute command
  214. (PerlString::s()) are obviously not done. However $& and $0-$9 are
  215. correctly expanded and substituted.
  216.  
  217. Also remember that if you want to put a \ in the regular expression
  218. then you must actually type \\ as the c compiler will interpret a \ for
  219. you. What happens to things like \t is up to your compiler.
  220.  
  221.  
  222. I/O
  223. ---
  224. I/O is done using standard c++ streams. I think this is ok, although
  225. some perl-ism maybe introduced one day.
  226. eg to copy a text file a line at a time:-
  227. {
  228. ifstream fin("file1.txt");
  229. ofstream fout("file2.txt");
  230. PerlString si;
  231.  
  232.     while(fin >> si) fout << si << endl;
  233. }
  234.  
  235. This will read the entire file into a PerlStringList:-
  236. {
  237. PerlStringList l;
  238. ifstream fin("file1.txt");
  239.  
  240.     fin >> l;
  241. }
  242.  
  243. One nifty outcome of using streams this way is the following syntax
  244. will load a PerlStringList and PerlList<T> in a reasonably compact
  245. way:-
  246. {
  247. PerlStringList slist;
  248. strstream ss;
  249.     ss << "one\n" << "two\nthree\nfour\n";
  250.     ss >> slist; // creates a 4 element string list
  251.  
  252. strstream iss;
  253. PerList<int> il;
  254.  
  255.     iss << "1 2 3 4 5 6 7 8 9 10" << endl; // quick load an integer array
  256.     iss >> il; // creates a 10 element integer list
  257. }
  258.  
  259.  
  260. Iterators
  261. ---------
  262. There is no iterator per-se, but all lists (including Assoc) allow
  263. an index to step through the list one by one. So iteration can be
  264. achieved, albeit clumsily.
  265. eg
  266.  
  267. PerlList<int> intlist;
  268.  
  269. for(int i=0;i<inlist.scalar();i++){
  270.     cout << intlist[i];
  271. }
  272.  
  273. foreach could be simulated with the following macro:-
  274.  
  275. #define FOREACH(var, array)\
  276.   for(int i=0;i<array.scalar() && (var=array[i], 1);i++)
  277.  
  278. eg
  279. {
  280.  
  281.     PerlList<int> fred;
  282.     int val, tot= 0;
  283.  
  284.     {    // this is useful to avoid the 'i' in the macro colliding
  285.     FOREACH(val, fred){
  286.         tot += val;
  287.     }
  288.     }
  289. }
  290.  
  291. A PerlList or PerlStringList may be used in an if statement to test
  292. if the list is empty or not.
  293. eg
  294. {
  295. PerlList<int> il;
  296.  
  297.     if(il) cout << "List is not empty" << endl;
  298.     else il.push(1);
  299. }
  300.  
  301. ==========
  302. Disclaimer
  303. ==========
  304.  
  305. This is a personal work, and SGI is not responsible for anything
  306. contained herein.
  307.